;*****************************************************************************************************
;+
; NAME:
;
;      eTEXT (enhanced TEXT)
;
; PURPOSE:
;
;      This is the enhanced version of the standard IDL XYOUTS
;      command. It uses the same syntax and support most of the IDL
;      plotting keywords. The output text is displayed in an IGL window
;      so that you can easily interact with it. Note that you can
;      directly use any Tex commands accepted by the TexToIDL
;      procedure (See TexToIDL documentation for more details).
; 
;
; CALLING SEQUENCE:
;
;      ePLOTS, x, y, str
;
; ARGUMENTS:
;
;     X:            The X coordinates used to position the string. A
;                   default of 0.5 is used if this is not provided.
;
;     Y:            The Y coordinates used to position the string. A
;                   default of 0.5 is used if this is not provided.
;
;     STR:          The string to be output. 
;                 
; KEYWORD PARAMETERS:
;
;     ALIGNMENT:    The alignment of the text baseline.
;                   0 = Left-justified (Default)
;                   1 = Centered
;                   2 = Right-justified
;
;     BACKGROUND:   Set this keyword to have a background for the
;                   string with a given color specified by BGCOLOR. 
;
;     BGCOLOR:      The name of the color when filling the
;                   text background (BACKGROUND=1). The default is !IGL_P.background
;
;     CHARSIZE:     The character size for the text (float). The default
;                   is !IGL_P.charsize
;
;     CHARTHICK:    The character thickness for the text (integer). The
;                   default is !IGL_P.charthick
;
;     COLOR:        The name of the color for the text. The default is !IGL_P.color
;
;     DATA:         Set this keyword to indicate that positioning
;                   parameters are given in data coordinates. In this
;                   case, there MUST be a valid coordinate
;                   system. Also note that the text is attached to
;                   the coordinate system. This is the default
;                   behaviour.
;
;     DEVICE:       Set this keyword to indicate that positioning
;                   parameters are given in device coordinates. This
;                   also prevents the text to be attached to any
;                   coordinate system.
;
;     FONT:         The character font for the text (integer).
;                   -1 : Herschey, 0 : Hardware, 1 : True Type. The
;                   default is !IGL_P.font
;
;     NOCLIP:       If set, prevent the clipping at the edge of the
;                   plot window. The default is to clip the text
;                   only if the data coordinates are used.
;
;     NODRAW:       *IGL ADDITION* : Set this keyword to prevent the
;                   current window to be refreshed. The text
;                   is added to the window but will not be
;                   visible until the window is refreshed (by calling
;                   another IGL plotting command for example). This is
;                   useful is you wish to issue several plotting
;                   commands but want to display the results only at
;                   the end.
;
;     NORMAL:       Set this keyword to indicate that positioning
;                   parameters are given in normalized coordinates. This
;                   also prevents the text to be attached to any
;                   coordinate system.
;
;     ORIENTATION:  Specify the counterclockwise angle in degrees from the
;                   horizontal to draw the text. The default is 0.0
;    
; PACKAGE:
;
;    Interactive Graphics Library (IGL)
;
; AUTHORS:
;
;        RAPHAEL SADOUN
;        Graduate Student
;        Institut d'Astrophysique de Paris
;        98 bis boulevard Arago
;        75014 PARIS FRANCE
;        E-mail: raphael.sadoun@gmail.com
;
;
; MODIFICATION HISTORY:
;
;     Written by: Raphael Sadoun, 24 April 2012
;-
;*****************************************************************************************************
PRO eTEXT, x, y, str, $
           ALIGNMENT=alignment, $
           BACKGROUND=background, $
           BGCOLOR=bgcolor, $
           CHARSIZE=charsize, $
           CHARTHICK=charthick, $
           COLOR=color, $
           DATA=data, $
           DEVICE=device, $
           FONT=font, $
           NOCLIP=noclip, $
           NODRAW=nodraw, $
           NORMAL=normal, $
           ORIENTATION=orientation
           

   COMPILE_OPT idl2, HIDDEN
   ON_ERROR, 2

   ;; Initialize the global system variables
   IGL_InitSysVars

   ;; Check positional arguments
   CASE N_PARAMS() OF
      
      0: message, 'No argument passed to eTEXT'
      
      1: BEGIN
         text = String(x)
         xloc = 0.5
         yloc = 0.5
      END
      
      2: BEGIN
         text = String(y)
         xloc = x
         yloc = 0.5
      END
      
      3: BEGIN
         text = String(str)
         xloc = x
         yloc = y
      END
      
   ENDCASE


   ;; Default keyword values
   IF N_Elements(alignment) EQ 0 THEN alignment = 0.0
   IF N_Elements(bgcolor) EQ 0 THEN bgcolor = !IGL_P.background
   IF N_Elements(charsize) EQ 0 THEN charsize = (!IGL_P.charsize LE 0) ? 1 : !IGL_P.charsize
   IF N_Elements(charthick) EQ 0 THEN charthick = (!IGL_P.charthick LE 0) ? 1 : !IGL_P.charthick
   IF N_Elements(color) EQ 0 THEN color = !IGL_P.color
   IF N_Elements(font) EQ 0 THEN font = !IGL_P.font
   IF N_Elements(orientation) EQ 0 THEN orientation = 0.0

   ;; Make sure we have a valid alignment
   textAlign = 0 > Round(alignment) < 2

   ;; Get current window
   currentWindow = IGL_GetCurrentWindow()
   IF OBJ_ISA_VALID(currentWindow,'IGL_Window') EQ 0 THEN message, 'No valid IGL window available'
   currentWindow -> GetProperty, Window_Xsize=Xsize, Window_Ysize=Ysize

   ;; Create the text object
   textObject = obj_new('IGL_TEXT',text, $
                        X=xloc, $
                        Y=yloc, $
                        ALIGNMENT=textAlign, $
                        BACKGROUND=Keyword_Set(background), $
                        BG_COLOR=bgcolor, $
                        CHARSIZE=charsize, $
                        COLOR=color, $
                        CLIP=0, $
                        THICKNESS=charthick, $
                        FONT=(font+1), $
                        ORIENTATION=orientation $
                        )


   ;; Create a coordinate system for the text
  
  IF Keyword_Set(device) THEN BEGIN ; Device coordinate system
     
     coords = Obj_New('IGL_Coord', $
                      POSITION=[0,0,1,1], $
                      XRANGE=[0,Xsize], $
                      YRANGE=[0,Ysize] $
                     )

     textObject -> SetProperty, Coord_Object=coords
     currentWindow -> AddGraphic, textObject
     
  ENDIF

  IF Keyword_Set(normal) THEN BEGIN ; Normalized coordinate system

     coords = Obj_New('IGL_Coord', $
                      POSITION=[0,0,1,1], $
                      XRANGE=[0,1], $
                      YRANGE=[0,1] $
                     )

     textObject -> SetProperty, Coord_Object=coords
     currentWindow -> AddGraphic, textObject
     
  ENDIF

  IF Keyword_Set(data) OR (N_Elements(coords) EQ 0) THEN BEGIN ; Data coordinate system

     ;; Get the current coordinate system
     currentCoords = IGL_GetSysVars('currentCoord')
     IF OBJ_ISA_VALID(currentCoords,'CatCoord') EQ 0 THEN Message, 'A coordinate system is not established'
     
     ;; Get the object that represents the coordinate system in the graphic
     currentCoords -> GetProperty, FIRST_PARENT=parent
     IF OBJ_VALID(parent) EQ 0 THEN Message, 'Invalid coordinate system'
     
     ;; Get the graphic in which the parent object is contained
     parent -> GetProperty, FIRST_PARENT=graphic
     IF OBJ_ISA_VALID(graphic,'IGL_Graphic') EQ 0 THEN message, 'Current coordinate system is not in a valid graphic'

     ;; Set polygon's properties
     textObject -> SetProperty, Coord_Object=currentCoords, Clip=1

     ;; Add the text to the coordinate system's owner
     parent -> Add, textObject

  ENDIF

  ;; Refresh the property editor
  currentWindow -> GetProperty, PropertyPanel=PropertyPanel
  IF OBJ_VALID(PropertyPanel) THEN PropertyPanel -> UpdateTreeBrowser
  
  ;; Draw window's content
  IF Keyword_set(nodraw) EQ 0 THEN currentWindow -> DrawWindow, /Buffered_Output 

END
